Claude Code SDK

Anthropic
Claude에서 열기
이 강좌에 대해 질문하기
노트 복사
LLM용 전체 강좌 노트 복사

Claude Code SDK를 사용하면 자신의 애플리케이션과 스크립트 내에서 Claude Code를 프로그래밍 방식으로 실행할 수 있습니다. TypeScript, Python, 그리고 CLI를 통해 사용할 수 있으며, 터미널에서 사용하던 것과 동일한 Claude Code 기능을 더 큰 워크플로에 통합하여 활용할 수 있습니다.

SDK는 이미 익숙한 것과 완전히 동일한 Claude Code를 실행합니다. 동일한 모든 도구에 접근할 수 있으며, 주어진 작업을 완료하기 위해 해당 도구들을 활용합니다. 이로 인해 자동화 및 통합 시나리오에서 특히 강력한 성능을 발휘합니다.

주요 기능

  • Claude Code를 프로그래밍 방식으로 실행
  • 터미널 버전과 동일한 Claude Code 기능 제공
  • 동일 디렉터리 내 Claude Code 인스턴스의 모든 설정 상속
  • 기본적으로 읽기 전용 권한
  • 대규모 파이프라인이나 도구의 일부로 활용할 때 가장 유용

기본 사용법

다음은 Claude에게 중복 쿼리를 분석하도록 요청하는 간단한 TypeScript 예제입니다: 

import { query } from "@anthropic-ai/claude-code";

const prompt = "Look for duplicate queries in the ./src/queries dir";

for await (const message of query({
  prompt,
})) {
  console.log(JSON.stringify(message, null, 2));
}

이 코드를 실행하면 로컬 Claude Code와 Claude 언어 모델 사이의 원시 대화를 메시지 단위로 확인할 수 있습니다. 마지막 메시지에는 Claude의 완전한 응답이 담겨 있습니다.

권한 및 도구

기본적으로 SDK는 읽기 전용 권한만 가집니다. 파일 읽기, 디렉터리 검색, grep 작업은 수행할 수 있지만, 파일을 쓰거나 편집하거나 생성할 수는 없습니다.

쓰기 권한을 활성화하려면 쿼리에 allowedTools 옵션을 추가하면 됩니다: 

for await (const message of query({
  prompt,
  options: {
    allowedTools: ["Edit"]
  }
})) {
  console.log(JSON.stringify(message, null, 2));
}

또는 프로젝트 전체 접근을 위해 .claude 디렉터리 내 설정 파일에서 권한을 구성할 수도 있습니다.

실용적인 활용 사례

Claude Code SDK는 더 큰 개발 워크플로에 통합될 때 진가를 발휘합니다. 다음과 같은 용도로 활용해 보세요:

  • 코드 변경 사항을 자동으로 검토하는 Git 훅
  • 코드를 분석하고 최적화하는 빌드 스크립트
  • 코드 유지보수 작업을 위한 헬퍼 명령어
  • 자동화된 문서 생성
  • CI/CD 파이프라인에서의 코드 품질 검사

SDK를 통해 프로그래밍 방식의 접근이 유용한 개발 프로세스의 어느 부분에든 AI 기반 지능을 추가할 수 있습니다.